Skip to main content
Web SDK Hero Light

​
Suki Ambient API

Use the Ambient Clinician Note Generation APIs to create clinical notes within your application. You can use these APIs to:
  • Send provider and encounter data.
  • Retrieve the generated clinical note.
  • Access the conversation transcript.
This allows you to seamlessly integrate Suki’s ambient documentation capabilities into your healthcare application and streamline clinical workflows.

​
How it works

To integrate with the Suki Ambient API, you will follow a session-based workflow. Here are the steps to create a note using Ambient APIs.
  1. Authenticate your session
    You must first sign in to get an access token (sdp_suki_token).
  2. Create a session
    Initiate a new session for a specific patient encounter. This returns an ambient_session_id that you will use for the next steps.
  3. Stream audio
    Send the real-time audio stream of the patient-clinician conversation to the Suki WebSocket endpoint.
  4. End the session
    Signal that the conversation is over. This action triggers the AI to begin generating the note.
  5. Retrieve the note
    Fetch the final, structured clinical note and the full transcript after the platform finishes processing.

​
Before you begin: Access & Credentials

To use the Suki Ambient API, you first need a set of partner credentials. To get your credentials, please contact our partnership team. They will guide you through the onboarding process and provide everything you need to get started.

​
Getting started with ambient APIs

Follow the steps below to create an ambient session and generate a clinical note from a conversation.
For complete technical specifications, please refer the relevant API Reference page.

​
Client < > Suki Interaction

To begin, you must authenticate to get your access token. Send a POST request to the /login endpoint with the following parameters in the request body:
  1. partner_id: Your unique partner ID, which we provide to you securely offline.
  2. partner_token: The user’s OAuth 2.0 ID token from your identity provider.
Suki verifies the partner_token using your publicly exposed JWKS endpoint (or your Okta authorization server URL if you use Okta). On a successful request, the API returns an access token called sdp_suki_token.You must include this sdp_suki_token in the authorization header for all subsequent API calls.Handling an unregistered userIf the user is not yet registered in our system, the /login request will fail. In this case, you must first call the /register endpoint to create the user, then call /login again.
Token Expiration: The sdp_suki_token has a limited lifetime. When it is about to expire, you can get a new one by making the same POST request to /login with a valid partner_token.
If a user is not yet registered, you must call the /register endpoint to register a new user in the Suki partner system.You only need to call this endpoint once for each new user.
The full API specification for this endpoint will be added here.
To start an ambient session, send a POST request to the /session/create endpoint with the following parameters in the request body:
This guide uses encounter_id. In older versions of the API, this parameter was named session_group_id. The old name will be deprecated in a future release.
  1. encounter_id: A unique identifier for the patient encounter (also called a visit). This can be any alphanumeric string up to 255 characters long.
  2. ambient_session_id (Optional): A UUID v4 to identify the session. If you do not provide one, Suki will generate it and include it in the response.
After creating the session, you can send a POST request to the /session/context endpoint to provide additional metadata.
Providing context significantly improves the accuracy of the generated clinical note.
Include the following parameters in the request body:
  1. provider_specialty (Optional): The specialty of the provider (e.g., “cardiology”).
  2. sections (Optional): A list of the clinical sections you want summarized, such as “Assessment and Plan” or “Chief Complaint”. If you do not provide this, a default set of sections will be used. See Appendix A for a list of standard sections.
  3. patient_info (Optional): An object containing the following patient information:
    • date_of_birth: The patient’s date of birth. This is used for accurate age calculation.
    • sex: The patient’s sex (MALE, FEMALE, OTHER, or UNKNOWN). Defaults to UNKNOWN.
Once you have created a session, you can begin streaming audio to it over a WebSocket connection.Connect to the WebSocket endpoint at wss://<your-suki-endpoint>/stream.Audio formatYou must stream raw audio data with the following specifications:
  • encoding: LINEAR16
  • sample_rate: 16KHz
  • channel: Mono
For optimal performance, we recommend chunking the audio into 100ms packets.WebSocket messagesThe WebSocket connection supports two types of messages: AUDIO and EVENT.
  • AUDIO: Carries the raw audio data in the required format.
  • EVENT: Signifies a specific action on the stream. The supported events are:
    • PAUSE: Pauses the audio stream.
    • RESUME: Resumes a paused audio stream.
    • CANCEL: Cancels the session. No note will be generated.
    • ABORT: Aborts the stream due to an interruption. A note will be generated from the audio received so far. The session remains active and can be resumed.
    • KEEP_ALIVE: Pings the server to keep the connection alive during periods of inactivity (e.g., when paused).
    • EOF: Indicates the end of the file or stream.
Stream behavior and timeouts
Keep the connection aliveYou must send a KEEP_ALIVE event at least once every five seconds when the stream is paused to prevent the connection from closing.
  1. Session Timeouts: If no audio data is sent for 25 seconds, Suki will disconnect the stream.
  2. Paused Stream: If the stream is paused and receiving KEEP_ALIVE events, Suki will disconnect the stream after 30 minutes of inactivity.
CANCEL vs. ABORT
  1. SendingCANCELterminates the session completely. No summary will be generated.
  2. SendingABORTends the current stream, but the session remains active. Suki will generate a note from the audio received before the interruption. You can resume streaming to the same ambient_session_id later.
To complete the session and begin the note generation process, send a POST request to the /session/end endpoint. This signals that no more audio will be sent for this session.Getting the generated noteOnce the note is ready, Suki notifies your application.The recommended way to know when a note is ready is to use a webhook. Suki will send a session_summary_generated event to a webhook endpoint that you provide.
Details on configuring your webhook and its authentication will be provided during the onboarding process.
Retrieving content manuallyAlternatively, you can use the following endpoints to check the status and retrieve the session’s content:
  1. GET /status: Check the processing status of a session.
  2. GET /content: Retrieve the final, structured clinical note.
  3. GET /transcript: Get the full conversation transcript, including timestamps for each part of the dialogue.
⌘I